Summary

• Auto-detect running Claude Code / Codex / OpenClaw processes and sync to Star Office
• Auto-join new instances, push state updates, auto-remove on exit
• Graceful shutdown cleans up all tracked agents

Implements #65.

Files

scripts/auto_detect/
├── __init__.py
├── README.md
├── detector.py    # process detection (pgrep + ps, merged & deduplicated)
├── client.py      # Star Office API client (join/push/leave/set_state)
└── daemon.py      # main polling loop + state sync

Pure addition — no changes to existing code.

Key design decisions

• No external dependencies — stdlib only (urllib, subprocess, json)
• pgrep + ps merged detection — both sources run every cycle and results are deduplicated, because pgrep and ps each miss different processes on macOS
• PID-sorted detection — stable disambiguation when multiple agents share the same working directory
• Push self-healing — 3 consecutive push failures trigger automatic re-join (handles backend restarts)
• Per-instance state isolation — state file path hashed from url+key, safe for multiple daemons
• Atomic state persistence — write-to-tmp-then-rename prevents corruption on crash

Usage

python scripts/auto_detect/daemon.py
python scripts/auto_detect/daemon.py --url https://office.hyacinth.im --key ocj_xxx --interval 15
python -m scripts.auto_detect.daemon  # module mode also works

Test plan

• Startup: detects all running Claude Code / Codex / OpenClaw instances
• New process auto-joins within one poll cycle
• Process exit triggers auto-leave within one poll cycle
• Push self-healing: stale agentId re-joins after 3 consecutive failures
• Persistent agents cleaned up when log file disappears
• Multi-instance: different keys use separate state files
• Graceful shutdown: SIGTERM cleans up all agents
• Module mode: python -m scripts.auto_detect.daemon works

概要

• 自动检测本机运行的 Claude Code / Codex / OpenClaw 进程，同步到 Star Office
• 新实例自动加入、推送状态更新、退出时自动移除
• 优雅关闭时清理所有已追踪的 agent

实现 #65。

关键设计决策

• 零外部依赖 — 仅使用标准库（urllib、subprocess、json）
• pgrep + ps 合并检测 — 每轮都跑两个来源并去重，因为 macOS 上 pgrep 和 ps 各自会漏掉不同的进程
• PID 排序 — 多个 agent 在同一工作目录时，消歧标签（如 #2）在每轮保持稳定
• Push 自愈 — 连续 3 次 push 失败后自动重新 join（应对后端重启等场景）
• 多实例状态隔离 — state 文件路径基于 url+key 做 hash，多个 daemon 同时跑互不干扰
• 原子化状态持久化 — 先写临时文件再 rename，防止 crash 时文件损坏

用法

python scripts/auto_detect/daemon.py
python scripts/auto_detect/daemon.py --url https://office.hyacinth.im --key ocj_xxx --interval 15
python -m scripts.auto_detect.daemon  # 也支持模块方式运行

Closes #65

🤖 Generated with Claude Code